import { Code } from '~/components/text/code'
import { HelpLink } from '~/components/text/link'
import Endpoint from '~/components/api/endpoint'
import Request from '~/components/api/request'

export const meta = {
  editUrl: 'pages/docs/api/v2/api-docs-mdx/endpoints/dns.mdx',
  lastEdited: '2019-10-17T14:44:04.000Z'
}

## DNS

### List all the DNS records of a domain

<Endpoint method="GET" url="/v2/domains/:domain/records" />

Get a list of DNS records created for a domain name specified in the URL.

#### Response Parameters

| Key         | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Description                                                                                                     |
| ----------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **id**      | <HelpLink href="#api-basics/types">ID</HelpLink>           | The unique ID of the DNS record. Always prepended with `rec_`.                                                  |
| **type**    | <HelpLink href="#api-basics/types">Enum</HelpLink>         | The type of record, it could be [any valid DNS record](https://en.wikipedia.org/wiki/List_of_DNS_record_types). |
| **name**    | <HelpLink href="#api-basics/types">String</HelpLink>       | A subdomain name or an empty string for the root domain.                                                        |
| **value**   | <HelpLink href="#api-basics/types">String</HelpLink>       | The record value.                                                                                               |
| **creator** | <HelpLink href="#api-basics/types">String</HelpLink>       | The ID of the user who created the record or `system` if the record is an automatic record.                     |
| **created** | <HelpLink href="#api-basics/types">String</HelpLink>       | A timestamp with the date when the record was created.                                                          |
| **updated** | <HelpLink href="#api-basics/types">String</HelpLink>       | A timestamp with the date when we created the deployment.                                                       |

##### Example Request

<Request url="https://api.zeit.co/v2/domains/zeit.rocks/records" auth />

##### Example Response

<Code lang="json">{`{
  "records": [
    {
      "id": "rec_38OtX1f51szRA03atCybBuZ3",
      "slug": "zeit.rocks.-address",
      "type": "ALIAS",
      "name": "",
      "value": "alias.zeit.co",
      "creator": "EvQtLv2F0FvfB5Vx4eK0R3Mf",
      "created": "1474631621542",
      "updated": null
    },
    {
      "id": "rec_Pxo2HEfutmlIYECtTE4SpDzY",
      "slug": "",
      "type": "CNAME",
      "name": "*",
      "value": "alias.zeit.co",
      "creator": "system",
      "created": "1474631619960",
      "updated": null
    }
  ]
}`}</Code>

### Create a new DNS record

<Endpoint method="POST" url="/v2/domains/:domain/records" />

Create a DNS record for a domain specified in the URL.

#### Request Parameters

| Key       | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                                                                                                     |
| --------- | ---------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| **name**  | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | A subdomain name or an empty string for the root domain.                                                        |
| **type**  | <HelpLink href="#api-basics/types">Enum</HelpLink>         | Yes      | The type of record, it could be [any valid DNS record](https://en.wikipedia.org/wiki/List_of_DNS_record_types). |
| **value** | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | The record value.                                                                                               |

##### Value

The following table defines the format of the `value` property for supported record types.

| Type      | Description                                                                                                     | Format                        | Example                     |
| --------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------- | --------------------------- |
| **A**     | An `A` record pointing to an IPv4 address.                                                                      | `address`                     | `192.0.2.42`                |
| **AAAA**  | An `AAAA` record pointing to an IPv6 address.                                                                   | `address`                     | `2001:DB8::42`              |
| **ALIAS** | An `ALIAS` virtual record pointing to a hostname resolved to an `A` record on server side.                      | `host`                        | `alias.zeit.co`             |
| **CAA**   | A `CAA` record to specify which Certificate Authorities (CAs) are allowed to issue certificates for the domain. | `flags tag value`             | `0 issue "letsencrypt.org"` |
| **CNAME** | A `CNAME` record mapping to another domain name.                                                                | `domain`                      | `alias.zeit.co`             |
| **MX**    | An `MX` record specifying the mail server responsible for accepting messages on behalf of the domain name.      | `priority host`               | `10 mail.zeit.rocks.`       |
| **SRV**   | A `SRV` record defining servers for specified services.                                                         | `priority weight port target` | `10 10 500 sip.zeit.rocks.` |
| **TXT**   | A `TXT` record containing arbitrary text.                                                                       | `text`                        | `hello`                     |

#### Response Parameters

| Key     | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Description                                                    |
| ------- | ---------------------------------------------------------- | -------------------------------------------------------------- |
| **uid** | <HelpLink href="#api-basics/types">String</HelpLink>       | The unique ID of the DNS record. Always prepended with `rec_`. |

##### Example Request

<Request
  method="POST"
  url="https://api.zeit.co/v2/domains/zeit.rocks/records"
  headers={{
    'Content-Type': 'application/json'
  }}
  auth
  body={{
    name: 'subdomain',
    type: 'MX',
    value: '10 mail.zeit.rocks'
  }}
/>

##### Example Response

<Code lang="json">{`{
  uid: "rec_V0fra8eEgQwEpFhYG2vTzC3K"
}`}</Code>

### Remove a DNS record

<Endpoint method="DELETE" url="/v2/domains/:domain/records/:recId" />

Delete a DNS record created for a domain name, where both the domain
and the record ID are specified in the URL. If the record was removed
successfully the endpoint returns with code 200 and an empty body.

##### Example Request

<Request
  method="DELETE"
  url="https://api.zeit.co/v2/domains/zeit.rocks/records/rec_V0fra8eEgQwEpFhYG2vTzC3K"
  auth
/>
